guide: document standalone OpenVMM releases#3988
Draft
benhillis wants to merge 15 commits into
Draft
Conversation
added 2 commits
July 20, 2026 17:42
Separate OpenVMM rolling releases from OpenHCL servicing and document the hybrid development-train, exact-tag, post-release bump, nightly, provenance, and support model. Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Define the latest-only pre-1.0 support policy and maintainer runbooks for normal and patch releases. Document tag-based source identity, official attested source archives, immutable publication, and the initial unsigned Windows artifact policy. Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Distinguish clean release-tag output from the explicit +dirty identity used for modified tagged checkouts. Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Guide documentation for a standalone OpenVMM (pre-1.0) release/support model, splitting it from the existing OpenHCL release-branch process and updating related Guide navigation/reference content.
Changes:
- Adds a new Guide page describing OpenVMM release cadence, tag semantics, and maintainer runbooks.
- Re-scopes the existing release management page to OpenHCL and cross-links between OpenVMM/OpenHCL release guidance.
- Updates the CLI reference and Guide SUMMARY to reflect the new documentation structure.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| Guide/src/SUMMARY.md | Splits the previous combined “Releases” entry into distinct OpenVMM vs OpenHCL pages. |
| Guide/src/reference/openvmm/management/cli.md | Documents --version/-V behavior in the CLI reference. |
| Guide/src/dev_guide/contrib/release.md | Renames/reframes the page as OpenHCL release management and adds cross-links/admonitions. |
| Guide/src/dev_guide/contrib/openvmm_release.md | New OpenVMM standalone release model/support policy + normal/patch runbooks. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (2)
Guide/src/dev_guide/contrib/release.md:19
- The opening sentence is duplicated, which reads like a copy/paste error and makes the paragraph awkward.
Occasionally, the OpenHCL project will declare upcoming release milestones. We
Occasionally, the OpenHCL project will declare upcoming release milestones. We
Guide/src/reference/openvmm/management/cli.md:13
- This
--versionbullet claims a tag/dirty/revision-based version format, but the current CLI uses clap’s built-in--versionoutput (derived from the Cargo package version), which is typically0.0.0for in-repo builds. Either update the implementation or keep the docs generic so they stay accurate.
* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
adds `+dirty`, and an untagged checkout reports a development version
containing the source revision.
benhillis
marked this pull request as draft
July 21, 2026 01:07
Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
Guide/src/reference/openvmm/management/cli.md:13
- The
--version/-Vdescription doesn't match the current implementation:Optionsis derived withclap::Parserand parsed viaOptions::parse, so clap will print the Cargo package version (it won't include git tag / dirty state / revision metadata as described here). This doc should reflect the actual output, or be softened to avoid specifying git/tag semantics that aren't implemented.
* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
adds `+dirty`, and an untagged checkout reports a development version
containing the source revision.
Remove internal process wording, document only the retained source revision metadata, and mark the tag-triggered automation as under development until the implementation stack lands. Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (3)
Guide/src/reference/openvmm/management/cli.md:13
- The
--versiondescription currently claims tag-derived OpenVMM source identity output, but theopenvmmCLI is clap-derived and (as of current code) reports the Cargo package version rather than a Git tag/revision-derived OpenVMM product version. This makes the CLI reference misleading until the versioning work lands.
* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
adds `+dirty`, and an untagged checkout reports a development version
containing the source revision.
Guide/src/dev_guide/contrib/openvmm_release.md:85
- This section describes tag-derived build identity as current behavior, but there doesn’t appear to be an implementation in-tree yet (e.g., no
openvmm-v*tag parsing logic, and other code still usesenv!("CARGO_PKG_VERSION")). Please mark this as the intended model (or date-qualify it) so readers don’t assume it already reflectsopenvmm --versiontoday.
OpenVMM resolves its displayed version from source identity:
Guide/src/dev_guide/contrib/openvmm_release.md:98
- This states that
openvmm --versionprints the tag-derived identity, but current code appears to still rely on Cargo package versioning (e.g.,env!("CARGO_PKG_VERSION")in the snapshot manifest). Until the tag-derived identity is implemented, this should be phrased as future/intended behavior (or explicitly note the current behavior).
`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.
Describe the source archive as behavior provided once the draft automation lands and align the OpenHCL navigation title with its page heading. Copilot-Session: 13086ab2-fa94-4be1-b276-ee1b96e7caea
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (2)
Guide/src/reference/openvmm/management/cli.md:13
- The
--versionbehavior described here (tag-derived version,+dirty, and Git revision) doesn’t match the current CLI implementation.openvmm_entry::cli_args::parse_options()callsOptions::parsewithout overriding clap’s version string, so--versioncomes from Cargo package metadata (seeopenvmm/openvmm_entry/src/cli_args.rs:40-66).
* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
adds `+dirty`, and an untagged checkout reports a development version
containing the source revision.
Guide/src/dev_guide/contrib/openvmm_release.md:101
- This section describes
openvmm --versionprinting a tag/Git-derived “displayed version”, but the current code uses Cargo package metadata for versioning (e.g.,env!("CARGO_PKG_VERSION")is recorded into snapshot manifests inopenvmm/openvmm_entry/src/vm_controller.rs:477). Unless the implementation has landed elsewhere, this should be phrased as planned/future behavior to avoid misleading readers.
`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.
A source tree with neither Git metadata nor generated release metadata warns
that `0.0.0-dev` is not an official release identity.
benhillis
commented
Jul 21, 2026
benhillis
commented
Jul 21, 2026
benhillis
commented
Jul 21, 2026
benhillis
commented
Jul 21, 2026
benhillis
commented
Jul 21, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (2)
Guide/src/reference/openvmm/management/cli.md:13
- The
--versiondescription doesn't match current behavior:openvmm_entry::Optionsis a plain#[derive(Parser)]without a customversionstring, so Clap's built-in--version/-Vprints the Cargo package version rather than a tag/dirty/source-revision identity. Either document the current output or clearly mark the tag-derived/source-identity output as under development (and link to the release-model page).
* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
adds `+dirty`, and an untagged checkout reports a development version
containing the source revision.
Guide/src/dev_guide/contrib/openvmm_release.md:90
- This section documents a specific source-identity/version-string scheme (
0.0.0-dev+g...,+dirty, build failure on multiple tags), but that behavior does not appear to be implemented in the current tree (andopenvmm_entrydoes not override Clap's default--version). To avoid the Guide becoming incorrect, mark this build-identity behavior as under development (similar to the later runbook note) or reword it as a proposed/target model.
## Build identity
OpenVMM resolves its displayed version from source identity:
Scope the Build identity section and the CLI --version reference as the intended (not yet implemented) model, since openvmm --version currently reports the Cargo package version. Addresses recurring review feedback.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
Guide/src/dev_guide/contrib/openvmm_release.md:160
- "
SHA256SUMScovers all nine archives" is a bit ambiguous when the list above includes 10 items (the nine archives plusSHA256SUMS). Consider wording that explicitly statesSHA256SUMScontains checksums for the nine archives listed above.
`SHA256SUMS` covers all nine archives. Every archive and `SHA256SUMS` receives a
public GitHub build provenance attestation before the release is published.
Distinguish the nine release archives from the SHA256SUMS checksum file in the release assets intro.
…e doc - Show the cargo build command in 'Building a release from source' and link to the Building OpenVMM page for prerequisites and options. - Add a 'Reporting security issues' section pointing to SECURITY.md/MSRC.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
Guide/src/dev_guide/contrib/release.md:23
- Prose line wrapping: this paragraph exceeds the style guide’s ~80-character wrap guideline for prose lines, which makes diffs harder to review (tables/code are exempt, but this is normal prose). Rewrap the paragraph to keep lines around 80 chars.
We stabilize the code base in a `release/<MAJOR>.<MINOR>.<YYMM>` branch, typically
named for the YYMM when the branch was forked. Future references to the release
number will be shortened to `<RELEASE>` in this doc. We expect a high quality
bar for all code that goes into the repository's main branch, and we ask
developers to hold these release branches to the highest quality standards. The
Clarify that pre-1.0 OpenVMM rolls forward from main (fixes, including security, ship in the next release, cut early when urgent) and that the patch-version scheme and Patch release runbook describe a post-1.0 release-branch servicing model. Keeps all sections; adds post-1.0 admonitions and cross-links.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
Guide/src/dev_guide/contrib/release.md:21
- This paragraph contains a very long prose line (not a table/code block). The Guide style guide asks to wrap prose at ~80 characters to keep diffs readable (Guide/src/dev_guide/contrib/style_guide.md). Consider wrapping the first sentence here.
Occasionally, the OpenHCL project will declare upcoming release milestones.
We stabilize the code base in a `release/<MAJOR>.<MINOR>.<YYMM>` branch, typically
named for the YYMM when the branch was forked. Future references to the release
number will be shortened to `<RELEASE>` in this doc. We expect a high quality
Comment on lines
+356
to
+357
| A confirmed security issue in the currently supported OpenVMM release ships as a | ||
| patch following the patch release runbook above. |
Add a downstream-packaging page covering how to build the `openvmm` gnu binary from the public source release, independent of the in-repo `.packages/` provisioning flow. The page records the empirically validated requirements: the native build dependencies (gcc, glibc-devel, kernel-headers, openssl-devel, a protobuf compiler), the two required environment overrides (PROTOC and OPENSSL_NO_VENDOR), the offline `cargo vendor` build model, and the runtime shared-library set. It clarifies that the gnu build uses the OpenSSL crypto backend and does not link SymCrypt (musl-only), and notes the workspace MSRV caveat. Includes a worked Azure Linux RPM example (BuildRequires/Requires and %build/%install) modeled on the cloud-hypervisor package, and links it from SUMMARY.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a7c0a618-7851-4fa6-9755-24402ff573e0
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (3)
Guide/src/dev_guide/contrib/openvmm_release.md:51
- This section sits immediately after an admonition stating patch releases are post-1.0 and "not produced yet", but the heading here reads as if patch releases are part of the current (pre-1.0) model. Tweaking the wording to explicitly scope patch releases to post-1.0 will avoid confusing readers about whether patch releases exist today.
Patch releases advance the patch version:
Guide/src/dev_guide/contrib/openvmm_release.md:62
- This paragraph describes patch-release behavioral guarantees immediately after stating that patch releases are not produced pre-1.0. As written it implies patch releases exist before 1.0. Consider explicitly scoping the patch-release guarantee to post-1.0 to keep the policy consistent within this section.
Before `1.0`, normal minor releases may make breaking changes to APIs,
command-line behavior, device models, snapshot formats, and other interfaces.
Breaking changes should be intentional and documented in the release notes,
with migration guidance when practical. Patch releases correct the currently
supported minor line and should not intentionally introduce breaking changes.
Guide/src/dev_guide/contrib/openvmm_release.md:153
- The text says "nine archives plus a separate SHA256SUMS" but the list that follows includes
SHA256SUMSas an item. Minor wording tweak can make the list and sentence align more directly.
The initial release contains nine archives plus a separate `SHA256SUMS`
checksum file:
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a7c0a618-7851-4fa6-9755-24402ff573e0
smalis-msft
reviewed
Jul 24, 2026
| @@ -1,16 +1,33 @@ | |||
| # Release Management | |||
| # OpenHCL Release Management | |||
Contributor
There was a problem hiding this comment.
nit: rename file to openhcl_release?
smalis-msft
reviewed
Jul 24, 2026
Comment on lines
+61
to
+62
| with migration guidance when practical. Patch releases correct the currently | ||
| supported minor line and should not intentionally introduce breaking changes. |
Contributor
There was a problem hiding this comment.
Maybe "unless absolutely necessary"? I could envision a scenario where some sort of breaking change is needed to fix an urgent security bug. Unlikely, but not impossible.
smalis-msft
reviewed
Jul 24, 2026
Comment on lines
+174
to
+175
| The public release workflow does not Authenticode-sign Windows artifacts. Do | ||
| not describe downloaded Windows executables as signed. |
Contributor
There was a problem hiding this comment.
Was this a command to the AI that slipped through?
smalis-msft
reviewed
Jul 24, 2026
Comment on lines
+342
to
+343
| For OpenHCL, maintainers cherry-pick a fix to each live OpenHCL release branch | ||
| that requires it. |
Contributor
There was a problem hiding this comment.
Why mention OpenHCL in the OpenVMM file?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Document the standalone pre-1.0 OpenVMM release and support model.
openvmm-vMAJOR.MINOR.PATCHtags are the public version authoritymainfirstThe guide includes normal-release and patch-release maintainer runbooks plus source-consumer verification guidance. Planned artifacts and automation are explicitly marked as under development until the draft implementation lands.
Draft implementation stack: #3989 and benhillis#5, #6, and #7.